Conversation
…rencing
When editing a deck with an AI agent or external tooling, there has been
no stable way to refer to a specific slide across turns: deictic references
("this slide") don't survive turns, page numbers shift on every insert or
delete, and titles or body fragments are rarely unique.
Reserve "key" as a well-known optional field in the per-page JSON config
to give downstream tooling a stable, opaque identifier for each slide.
- Optional, opaque string with no rendering effect (treated similarly to
"freeze" / "skip" / "ignore" in that it never appears in the rendered
output).
- Empty values are treated as unset.
- Uniqueness is enforced at parse time so that consumers can rely on the
identity guarantee instead of treating it as convention.
Refs: #523
golangci-lint funcorder requires unexported methods to come after the struct's exported methods. The unexported validateKeys sat between Parse and ToSlides, which tripped the linter on CI.
Contributor
Code Metrics Report
Details | | main (f9697fd) | #527 (8c8526d) | +/- |
|---------------------|----------------|----------------|-------|
+ | Coverage | 33.7% | 33.9% | +0.2% |
| Files | 31 | 31 | 0 |
| Lines | 3405 | 3416 | +11 |
+ | Covered | 1150 | 1161 | +11 |
+ | Code to Test Ratio | 1:0.9 | 1:0.9 | +0.0 |
| Code | 7018 | 7037 | +19 |
+ | Test | 6578 | 6616 | +38 |
- | Test Execution Time | 12s | 14s | +2s |Code coverage of files in pull request scope (79.2% → 79.7%)
Reported by octocov |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs: #523
This pull request reserves
keyas a well-known optional field in the per-page JSON configuration comment, so that AI agents and external tooling can refer to a specific slide by a stable, opaque identifier instead of relying on page numbers, headings, or body fragments — all of which shift or collide in practice.Behavior:
keyis optional and opaque; deck does not interpret its content, length, or character set.keydoes not trigger a slide update).keycauseParseto returnduplicate page key %q at pages %d and %d, so downstream consumers can rely on the identity guarantee rather than treating it as a convention.Example:
Changes:
Keyfield tomd.Configandmd.Content, and copy it through when parsing the page-config HTML comment.validateKeysand call it frommd.Parseafter defaults are reflected.README.md(page configuration section and the agent-facing guide) to documentkey.testdata/key.md(+ golden) toTestParseand a newTestValidateKeyscovering: no keys, all unique, mixed keyed/unkeyed, empty-key collisions (not duplicates), and a duplicate-key error.Verified with
go build ./...andgo test ./...(all packages pass).